/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.configuration;
import java.io.BufferedReader;
import java.io.File;
import java.io.IOException;
import java.io.PrintWriter;
import java.io.Reader;
import java.io.Writer;
import java.net.URL;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.Set;
import org.apache.commons.collections.set.ListOrderedSet;
import org.apache.commons.configuration.tree.ConfigurationNode;
import org.apache.commons.configuration.tree.DefaultConfigurationNode;
import org.apache.commons.configuration.tree.ViewNode;
import org.apache.commons.lang.StringUtils;
/**
* <p>
* A specialized hierarchical configuration implementation for parsing ini
* files.
* </p>
* <p>
* An initialization or ini file is a configuration file typically found on
* Microsoft's Windows operating system and contains data for Windows based
* applications.
* </p>
* <p>
* Although popularized by Windows, ini files can be used on any system or
* platform due to the fact that they are merely text files that can easily be
* parsed and modified by both humans and computers.
* </p>
* <p>
* A typcial ini file could look something like:
* </p>
* <code>
* [section1]<br>
* ; this is a comment!<br>
* var1 = foo<br>
* var2 = bar<br>
* <br>
* [section2]<br>
* var1 = doo<br>
* </code>
* <p>
* The format of ini files is fairly straight forward and is composed of three
* components:<br>
* <ul>
* <li><b>Sections:</b> Ini files are split into sections, each section starting
* with a section declaration. A section declaration starts with a '[' and ends
* with a ']'. Sections occur on one line only.</li>
* <li><b>Parameters:</b> Items in a section are known as parameters. Parameters
* have a typical <code>key = value</code> format.</li>
* <li><b>Comments:</b> Lines starting with a ';' are assumed to be comments.</li>
* </ul>
* </p>
* <p>
* There are various implementations of the ini file format by various vendors
* which has caused a number of differences to appear. As far as possible this
* configuration tries to be lenient and support most of the differences.
* </p>
* <p>
* Some of the differences supported are as follows:
* <ul>
* <li><b>Comments:</b> The '#' character is also accepted as a comment
* signifier.</li>
* <li><b>Key value separtor:</b> The ':' character is also accepted in place of
* '=' to separate keys and values in parameters, for example
* <code>var1 : foo</code>.</li>
* <li><b>Duplicate sections:</b> Typically duplicate sections are not allowed,
* this configuration does however support it. In the event of a duplicate
* section, the two section's values are merged.</li>
* <li><b>Duplicate parameters:</b> Typically duplicate parameters are only
* allowed if they are in two different sections, thus they are local to
* sections; this configuration simply merges duplicates; if a section has a
* duplicate parameter the values are then added to the key as a list.</li>
* </ul>
* </p>
* <p>
* Global parameters are also allowed; any parameters declared before a section
* is declared are added to a global section. It is important to note that this
* global section does not have a name.
* </p>
* <p>
* In all instances, a parameter's key is prepended with its section name and a
* '.' (period). Thus a parameter named "var1" in "section1" will have the key
* <code>section1.var1</code> in this configuration. (This is the default
* behavior. Because this is a hierarchical configuration you can change this by
* setting a different {@link org.apache.commons.configuration.tree.ExpressionEngine}.)
* </p>
* <p>
* <h3>Implementation Details:</h3> Consider the following ini file:<br>
* <code>
* default = ok<br>
* <br>
* [section1]<br>
* var1 = foo<br>
* var2 = doodle<br>
* <br>
* [section2]<br>
* ; a comment<br>
* var1 = baz<br>
* var2 = shoodle<br>
* bad =<br>
* = worse<br>
* <br>
* [section3]<br>
* # another comment<br>
* var1 : foo<br>
* var2 : bar<br>
* var5 : test1<br>
* <br>
* [section3]<br>
* var3 = foo<br>
* var4 = bar<br>
* var5 = test2<br>
* </code>
* </p>
* <p>
* This ini file will be parsed without error. Note:
* <ul>
* <li>The parameter named "default" is added to the global section, it's value
* is accessed simply using <code>getProperty("default")</code>.</li>
* <li>Section 1's parameters can be accessed using
* <code>getProperty("section1.var1")</code>.</li>
* <li>The parameter named "bad" simply adds the parameter with an empty value.</li>
* <li>The empty key with value "= worse" is added using a key consisting of a
* single space character. This key is still added to section 2 and the value
* can be accessed using <code>getProperty("section2. ")</code>, notice the
* period '.' and the space following the section name.</li>
* <li>Section three uses both '=' and ':' to separate keys and values.</li>
* <li>Section 3 has a duplicate key named "var5". The value for this key is
* [test1, test2], and is represented as a List.</li>
* </ul>
* </p>
* <p>
* Internally, this configuration maps the content of the represented ini file
* to its node structure in the following way:
* <ul>
* <li>Sections are represented by direct child nodes of the root node.</li>
* <li>For the content of a section, corresponding nodes are created as children
* of the section node.</li>
* </ul>
* This explains how the keys for the properties can be constructed. You can
* also use other methods of {@link HierarchicalConfiguration} for querying or
* manipulating the hierarchy of configuration nodes, for instance the
* <code>configurationAt()</code> method for obtaining the data of a specific
* section.
* </p>
* <p>
* The set of sections in this configuration can be retrieved using the
* <code>getSections()</code> method. For obtaining a
* <code>SubnodeConfiguration</code> with the content of a specific section the
* <code>getSection()</code> method can be used.
* </p>
* <p>
* <em>Note:</em> Configuration objects of this type can be read concurrently by
* multiple threads. However if one of these threads modifies the object,
* synchronization has to be performed manually.
* </p>
*
* @author <a
* href="http://commons.apache.org/configuration/team-list.html">Commons
* Configuration team</a>
* @version $Id: HierarchicalINIConfiguration.java 720295 2008-11-24 21:29:42Z oheger $
* @since 1.6
*/
public class HierarchicalINIConfiguration extends
AbstractHierarchicalFileConfiguration
{
/**
* The characters that signal the start of a comment line.
*/
protected static final String COMMENT_CHARS = "#;";
/**
* The characters used to separate keys from values.
*/
protected static final String SEPARATOR_CHARS = "=:";
/**
* The serial version UID.
*/
private static final long serialVersionUID = 2548006161386850670L;
/**
* Constant for the line separator.
*/
private static final String LINE_SEPARATOR = System.getProperty("line.separator");
/**
* The line continuation character.
*/
private static final String LINE_CONT = "\\";
/**
* Create a new empty INI Configuration.
*/
public HierarchicalINIConfiguration()
{
super();
}
/**
* Create and load the ini configuration from the given file.
*
* @param filename The name pr path of the ini file to load.
* @throws ConfigurationException If an error occurs while loading the file
*/
public HierarchicalINIConfiguration(String filename)
throws ConfigurationException
{
super(filename);
}
/**
* Create and load the ini configuration from the given file.
*
* @param file The ini file to load.
* @throws ConfigurationException If an error occurs while loading the file
*/
public HierarchicalINIConfiguration(File file)
throws ConfigurationException
{
super(file);
}
/**
* Create and load the ini configuration from the given url.
*
* @param url The url of the ini file to load.
* @throws ConfigurationException If an error occurs while loading the file
*/
public HierarchicalINIConfiguration(URL url) throws ConfigurationException
{
super(url);
}
/**
* Save the configuration to the specified writer.
*
* @param writer - The writer to save the configuration to.
* @throws ConfigurationException If an error occurs while writing the
* configuration
*/
public void save(Writer writer) throws ConfigurationException
{
PrintWriter out = new PrintWriter(writer);
Iterator it = getSections().iterator();
while (it.hasNext())
{
String section = (String) it.next();
if (section != null)
{
out.print("[");
out.print(section);
out.print("]");
out.println();
}
Configuration subset = getSection(section);
Iterator keys = subset.getKeys();
while (keys.hasNext())
{
String key = (String) keys.next();
Object value = subset.getProperty(key);
if (value instanceof Collection)
{
Iterator values = ((Collection) value).iterator();
while (values.hasNext())
{
value = (Object) values.next();
out.print(key);
out.print(" = ");
out.print(formatValue(value.toString()));
out.println();
}
}
else
{
out.print(key);
out.print(" = ");
out.print(formatValue(value.toString()));
out.println();
}
}
out.println();
}
out.flush();
}
/**
* Load the configuration from the given reader. Note that the
* <code>clear</code> method is not called so the configuration read in will
* be merged with the current configuration.
*
* @param reader The reader to read the configuration from.
* @throws ConfigurationException If an error occurs while reading the
* configuration
*/
public void load(Reader reader) throws ConfigurationException
{
try
{
BufferedReader bufferedReader = new BufferedReader(reader);
ConfigurationNode sectionNode = getRootNode();
String line = bufferedReader.readLine();
while (line != null)
{
line = line.trim();
if (!isCommentLine(line))
{
if (isSectionLine(line))
{
String section = line.substring(1, line.length() - 1);
sectionNode = getSectionNode(section);
}
else
{
String key = "";
String value = "";
int index = line.indexOf("=");
if (index >= 0)
{
key = line.substring(0, index);
value = parseValue(line.substring(index + 1), bufferedReader);
}
else
{
index = line.indexOf(":");
if (index >= 0)
{
key = line.substring(0, index);
value = parseValue(line.substring(index + 1), bufferedReader);
}
else
{
key = line;
}
}
key = key.trim();
if (key.length() < 1)
{
// use space for properties with no key
key = " ";
}
ConfigurationNode node = createNode(key);
node.setValue(value);
sectionNode.addChild(node);
}
}
line = bufferedReader.readLine();
}
}
catch (IOException e)
{
throw new ConfigurationException(
"Unable to load the configuration", e);
}
}
/**
* Parse the value to remove the quotes and ignoring the comment. Example:
*
* <pre>
* "value" ; comment -> value
* </pre>
*
* <pre>
* 'value' ; comment -> value
* </pre>
*
* @param val the value to be parsed
* @param reader the reader (needed if multiple lines have to be read)
* @throws IOException if an IO error occurs
*/
private static String parseValue(String val, BufferedReader reader) throws IOException
{
StringBuffer propertyValue = new StringBuffer();
boolean lineContinues;
String value = val.trim();
do
{
boolean quoted = value.startsWith("\"") || value.startsWith("'");
boolean stop = false;
boolean escape = false;
char quote = quoted ? value.charAt(0) : 0;
int i = quoted ? 1 : 0;
StringBuffer result = new StringBuffer();
while (i < value.length() && !stop)
{
char c = value.charAt(i);
if (quoted)
{
if ('\\' == c && !escape)
{
escape = true;
}
else if (!escape && quote == c)
{
stop = true;
}
else if (escape && quote == c)
{
escape = false;
result.append(c);
}
else
{
if (escape)
{
escape = false;
result.append('\\');
}
result.append(c);
}
}
else
{
if (!isCommentChar(c))
{
result.append(c);
}
else
{
stop = true;
}
}
i++;
}
String v = result.toString();
if (!quoted)
{
v = v.trim();
lineContinues = lineContinues(v);
if (lineContinues)
{
// remove trailing "\"
v = v.substring(0, v.length() - 1).trim();
}
}
else
{
lineContinues = lineContinues(value, i);
}
propertyValue.append(v);
if (lineContinues)
{
propertyValue.append(LINE_SEPARATOR);
value = reader.readLine();
}
} while (lineContinues && value != null);
return propertyValue.toString();
}
/**
* Tests whether the specified string contains a line continuation marker.
*
* @param line the string to check
* @return a flag whether this line continues
*/
private static boolean lineContinues(String line)
{
String s = line.trim();
return s.equals(LINE_CONT)
|| (s.length() > 2 && s.endsWith(LINE_CONT) && Character
.isWhitespace(s.charAt(s.length() - 2)));
}
/**
* Tests whether the specified string contains a line continuation marker
* after the specified position. This method parses the string to remove a
* comment that might be present. Then it checks whether a line continuation
* marker can be found at the end.
*
* @param line the line to check
* @param pos the start position
* @return a flag whether this line continues
*/
private static boolean lineContinues(String line, int pos)
{
String s;
if (pos >= line.length())
{
s = line;
}
else
{
int end = pos;
while (end < line.length() && !isCommentChar(line.charAt(end)))
{
end++;
}
s = line.substring(pos, end);
}
return lineContinues(s);
}
/**
* Tests whether the specified character is a comment character.
*
* @param c the character
* @return a flag whether this character starts a comment
*/
private static boolean isCommentChar(char c)
{
return COMMENT_CHARS.indexOf(c) >= 0;
}
/**
* Add quotes around the specified value if it contains a comment character.
*/
private String formatValue(String value)
{
boolean quoted = false;
for (int i = 0; i < COMMENT_CHARS.length() && !quoted; i++)
{
char c = COMMENT_CHARS.charAt(i);
if (value.indexOf(c) != -1)
{
quoted = true;
}
}
if (quoted)
{
return '"' + StringUtils.replace(value, "\"", "\\\"") + '"';
}
else
{
return value;
}
}
/**
* Determine if the given line is a comment line.
*
* @param line The line to check.
* @return true if the line is empty or starts with one of the comment
* characters
*/
protected boolean isCommentLine(String line)
{
if (line == null)
{
return false;
}
// blank lines are also treated as comment lines
return line.length() < 1 || COMMENT_CHARS.indexOf(line.charAt(0)) >= 0;
}
/**
* Determine if the given line is a section.
*
* @param line The line to check.
* @return true if the line contains a secion
*/
protected boolean isSectionLine(String line)
{
if (line == null)
{
return false;
}
return line.startsWith("[") && line.endsWith("]");
}
/**
* Return a set containing the sections in this ini configuration. Note that
* changes to this set do not affect the configuration.
*
* @return a set containing the sections.
*/
public Set getSections()
{
Set sections = new ListOrderedSet();
boolean globalSection = false;
for (Iterator it = getRootNode().getChildren().iterator(); it.hasNext();)
{
ConfigurationNode node = (ConfigurationNode) it.next();
if (isSectionNode(node))
{
if (globalSection)
{
sections.add(null);
globalSection = false;
}
sections.add(node.getName());
}
else
{
globalSection = true;
}
}
return sections;
}
/**
* Returns a configuration with the content of the specified section. This
* provides an easy way of working with a single section only. The way this
* configuration is structured internally, this method is very similar to
* calling
* <code>{@link HierarchicalConfiguration#configurationAt(String)}</code>
* with the name of the section in question. There are the following
* differences however:
* <ul>
* <li>This method never throws an exception. If the section does not exist,
* an empty configuration is returned.</li>
* <li>There is special support for the global section: Passing in
* <b>null</b> as section name returns a configuration with the content of
* the global section (which may also be empty).</li>
* </ul>
*
* @param name the name of the section in question; <b>null</b> represents
* the global section
* @return a configuration containing only the properties of the specified
* section
*/
public SubnodeConfiguration getSection(String name)
{
if (name == null)
{
return getGlobalSection();
}
else
{
try
{
return configurationAt(name);
}
catch (IllegalArgumentException iex)
{
// the passed in key does not map to exactly one node
// return an empty configuration
return new SubnodeConfiguration(this,
new DefaultConfigurationNode());
}
}
}
/**
* Obtains the node representing the specified section. This method is
* called while the configuration is loaded. If a node for this section
* already exists, it is returned. Otherwise a new node is created.
*
* @param sectionName the name of the section
* @return the node for this section
*/
private ConfigurationNode getSectionNode(String sectionName)
{
List nodes = getRootNode().getChildren(sectionName);
if (!nodes.isEmpty())
{
return (ConfigurationNode) nodes.get(0);
}
ConfigurationNode node = createNode(sectionName);
markSectionNode(node);
getRootNode().addChild(node);
return node;
}
/**
* Creates a sub configuration for the global section of the represented INI
* configuration.
*
* @return the sub configuration for the global section
*/
private SubnodeConfiguration getGlobalSection()
{
ViewNode parent = new ViewNode();
for (Iterator it = getRootNode().getChildren().iterator(); it.hasNext();)
{
ConfigurationNode node = (ConfigurationNode) it.next();
if (!isSectionNode(node))
{
parent.addChild(node);
}
}
return createSubnodeConfiguration(parent);
}
/**
* Marks a configuration node as a section node. This means that this node
* represents a section header. This implementation uses the node's
* reference property to store a flag.
*
* @param node the node to be marked
*/
private static void markSectionNode(ConfigurationNode node)
{
node.setReference(Boolean.TRUE);
}
/**
* Checks whether the specified configuration node represents a section.
*
* @param node the node in question
* @return a flag whether this node represents a section
*/
private static boolean isSectionNode(ConfigurationNode node)
{
return node.getReference() != null || node.getChildrenCount() > 0;
}
}